# 使用指南

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

本文作为 **Quectel Pi M1/L1** Linux 系统的集中使用入口，把供电、连接、网络、显示、摄像头、多媒体、存储和扩展接口的核心使用方法汇总，便于快速查阅。

# 上电与供电

Quectel Pi 通过 POWER IN Type‑C 口作为主供电入口。推荐使用具备 5 V / 5 A 输出能力的电源适配器和配套线材；不建议使用低于 3 A 的电源，否则可能出现启动异常、系统死机、外设不稳定或高负载下掉电等问题。

上电前应确认拨码开关、显示屏、摄像头、USB 外设、扩展板等连接状态。MIPI、摄像头、HDMI、USB 大功率外设和 40‑pin 扩展接口建议断电后再插拔，避免带电操作造成通信异常或硬件损坏。连接供电线后，长按板侧 PWRKEY 直到系统启动；电源指示灯常亮后，等待系统完成启动，再通过 ADB、串口、显示器或网络方式进入系统。

USB Type‑C 调试/烧录接口不要与 POWER IN 供电口混淆。USB Device 模式主要用于 ADB、烧录和上位机交互，不用于外接 U 盘、键鼠等 USB 外设；USB Host 模式可连接 U 盘、键鼠、USB 摄像头等普通外设，但大功率模块建议使用外部供电。

# 默认网络端口开放说明

系统默认端口策略遵循最小开放原则。需要外部主机访问的服务才监听在全网地址或网卡地址上；仅供本机内部组件使用的服务应监听在回环地址上。默认对外开放端口以 **TCP 22（SSH）** 为主，用于远程登录和维护。

| **协议/端口** | **默认监听范围** | **用途** | **说明** |
| --- | --- | --- | --- |
| TCP 22 | 外部可达地址 | SSH 远程登录 | 用于开发、调试和维护。设备获取有效 IP 且网络可达后，可通过 SSH 访问。 |
| TCP 5037 | `127.0.0.1` | ADB 本地服务 | 仅供本机 ADB 相关进程通信，不作为外部网络端口开放。 |
| TCP 9083 | `127.0.0.1` | 本机 port bridge | 仅供开发板本机内部服务使用。 |
| TCP/UDP 53 | `127.0.0.53` / `127.0.0.54` | 本机 DNS 解析 | 用于本机域名解析，不对外提供 DNS 服务。 |
| UDP 323 | `127.0.0.1` / `::1` | 本机时间同步 | 仅本机使用，默认不对外提供时间同步服务。 |

3389（RDP/xrdp）、5900（VNC）、80/443（HTTP/HTTPS）等常见服务端口默认不作为外部服务开放。只有用户自行安装、启用并配置对应服务后，才可能出现监听和外部访问能力。

# 设备连接方式

## ADB 终端

ADB 适合开发阶段本地调试、进入 Shell、传输文件、重启设备和执行一次性命令。使用 USB Type‑C 数据线连接主机和开发板后，在主机侧准备 platform-tools 或系统自带 adb 工具，即可使用 ADB 管理设备。

```bash
adb devices -l
adb shell
adb push ./file.txt /data/
adb pull /data/file.txt ./
adb reboot
```

开发板侧通常已集成 `adbd.service`。如需确认服务状态，可在本地终端或串口中执行：

```bash
systemctl status adbd.service --no-pager -l
```

## Debug UART 串口

Debug UART 不依赖网络和图形界面，适合启动日志查看、系统无法进入、显示异常、网络异常等底层问题定位。连接时需使用支持 3.3 V 电平的 USB 转 TTL 串口小板，并按 TX/RX/GND 正确接线。

Linux 主机侧可使用串口工具连接，常见波特率为 115200，实际设备节点以主机识别结果为准：

```bash
ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
picocom -b 115200 /dev/ttyUSB0
```

若无输出或乱码，应优先检查 TX/RX 是否交叉连接、GND 是否共地、波特率是否一致、串口小板驱动是否正常。

## SSH 远程终端与 SCP 文件传输

SSH 用于网络可达后的远程命令行登录；SCP 用于基于 SSH 的文件传输。使用前需确认开发板已通过以太网、Wi‑Fi 或蜂窝网络获取 IP，且 SSH 服务处于运行状态。

```bash
ip -br addr
systemctl status ssh --no-pager
ssh <用户名>@<设备IP>
scp ./file.txt <用户名>@<设备IP>:/home/<用户名>/
scp -r ./project <用户名>@<设备IP>:/home/<用户名>/
```

若无法连接，先确认 IP 是否正确、主机与开发板是否网络可达、22 端口是否监听、用户名和密码是否正确。

## 图形远程桌面

图形远程桌面适合需要远程查看或操作 Linux 桌面的场景。M1 可使用系统集成的图形远程桌面能力；L1 可根据镜像支持情况使用 Weston RDP backend。远程桌面需要设备与控制端网络互通，并且图形会话或远程桌面服务已启动。

如果使用 TeamViewer，应确保设备端和控制端均能访问公网，并完成设备 ID、密码或账号绑定配置。TeamViewer 更适合跨网络远程维护；RDP 更适合同一局域网内访问。

## Samba 与 Apache 服务

Samba 可用于局域网文件共享，Apache 可用于提供简单 Web 页面或文件服务。两类服务都依赖网络可达、服务已启动、共享目录或网页目录配置正确，并可能涉及访问账号、密码和目录权限。

```bash
systemctl status smb --no-pager 2>/dev/null || systemctl status smbd --no-pager
systemctl status apache2 --no-pager 2>/dev/null || systemctl status httpd --no-pager
ip -br addr
ss -lntup
```

若产品场景不需要文件共享或 Web 服务，建议保持未启用状态，避免不必要的网络暴露面。

# qpi-config 常用配置

`qpi-config` 用于查看和配置板端常用功能，包括 LED、桌面环境、温度、系统状态和 Wi‑Fi。本文按 Linux 命令行口径整理，不依赖 Debian 桌面流程。

```bash
qpi-config dump temperature
qpi-config dump systemusage
qpi-config led get
qpi-config wifi scan
```

如果使用 `qpi-config` 配置 Wi‑Fi，仍需以实际镜像支持的后端为准；若需要手动连接 Wi‑Fi，优先参考本文 Wi‑Fi 章节中的 `wpa_supplicant` / `wpa_cli` 流程。

# 显示功能

显示部分包含 MIPI‑DSI 和 Micro HDMI 两类输出。连接或切换显示接口前建议断电操作。MIPI 与 HDMI 的显示能力、触摸链路和音视频链路取决于屏幕、排线、触摸 USB 线和系统图形环境配置。

## MIPI 显示

MIPI 屏通常通过 DSI 排线连接，并可配合触摸功能使用。确认显示异常时，应检查排线方向、锁扣、背光、触摸线和系统显示节点。

```bash
ls /sys/class/drm/
cat /sys/class/backlight/*/brightness 2>/dev/null
cat /sys/class/backlight/*/max_brightness 2>/dev/null
```

## HDMI 显示

HDMI 适合外接显示器或带触摸屏幕。带触摸的 HDMI 屏通常还需要单独连接 USB 触摸线。若 HDMI 无显示，可先检查线材、显示器输入源、分辨率模式和 DRM 状态。

```bash
cat /sys/class/drm/card0-HDMI-A-1/status 2>/dev/null
cat /sys/class/drm/card0-HDMI-A-1/modes 2>/dev/null
```

# 摄像头功能

摄像头文档主要覆盖 MIPI CSI 摄像头，示例配件为 IMX219。使用前应确认摄像头型号、FPC 排线方向、接口位置和锁扣状态。摄像头异常时，优先检查硬件连接，其次查看视频节点和采集格式。

```bash
ls /dev/video*
v4l2-ctl --list-devices 2>/dev/null
v4l2-ctl --list-formats-ext -d /dev/video0 2>/dev/null
```

预览、拍照和录像可根据镜像提供的 GStreamer、v4l2 或应用层工具执行。双摄使用时需确认两个摄像头分别被系统识别，并避免排线、供电或 lane 配置错误。

# Wi‑Fi 与蓝牙

## Wi‑Fi 连接（Linux / wpa_supplicant）

Wi‑Fi 连接按 Linux 命令行方式整理，主流程使用 `wpa_supplicant` / `wpa_cli`，不使用 `nmcli`。连接前确认无线接口名称，常见为 `wlan0`。

```bash
ip link show wlan0
rfkill list 2>/dev/null
ip link set wlan0 up
```

可使用 `wpa_passphrase` 生成配置并启动 `wpa_supplicant`：

```bash
wpa_passphrase "SSID名称" "Wi-Fi密码" > /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
udhcpc -i wlan0 2>/dev/null || dhclient wlan0
ip addr show wlan0
ip route
ping -c 4 8.8.8.8
```

也可以使用 `wpa_cli` 交互式连接：

```
wpa_cli -i wlan0
> scan
> scan_results
> add_network
> set_network 0 ssid "\"SSID名称\""
> set_network 0 psk "\"Wi-Fi密码\""
> enable_network 0
> save_config
> status
```

当 `wpa_state=COMPLETED` 且接口获取到有效 IP 时，说明认证和地址获取基本正常。若扫描不到热点，应检查天线、rfkill、驱动固件和信号环境。

## 蓝牙连接

蓝牙功能可通过 `bluetoothctl` 操作。连接前确认蓝牙服务已运行，目标设备处于可发现或可配对状态。

```bash
systemctl status bluetooth --no-pager
bluetoothctl
```

```
power on
agent on
default-agent
scan on
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX
scan off
quit
```

# 蜂窝网络

蜂窝网络通过 USIM 卡接入运营商 LTE 网络。系统启动后会自动完成 modem 初始化、SIM 识别、运营商注网和数据拨号；正常情况下无需用户手动执行拨号命令。插入有效 USIM 卡并连接蜂窝天线后，注网成功时系统会生成 `rmnet_data0` 等蜂窝数据接口并获取 IP 地址。

```bash
ifconfig rmnet_data0 2>/dev/null || ip addr show rmnet_data0
ip route
ping -c 4 8.8.8.8
ping -c 4 www.baidu.com
```

若 `rmnet_data0` 不存在或无 IP，优先检查 SIM 卡方向、套餐状态、天线连接、信号覆盖、modem 初始化状态和 APN 配置。若系统集成 ModemManager，可使用 `mmcli -L`、`mmcli -m 0` 查看 modem/SIM 状态。

# GNSS 定位

GNSS 定位测试前需连接 GNSS 天线，并尽量将天线放置在室外、窗边或无遮挡位置。室内、屏蔽环境、天线未连接或方向不正确，都可能导致长时间无法搜星或无法定位。

定位验收优先使用 `garden_app`；`qlril-api-test` 主要用于 QLRIL / 蜂窝通信 API 测试，只作为辅助验证。

```bash
command -v garden_app
command -v qlril-api-test
garden_app -h
garden_app -n -y -t 120 -o 120
garden_app -n -y -t 120 -A 4 -B 28
```

`-n` 用于输出 NMEA，`-y` 用于输出可见卫星信息，`-t` 设置测试时长，`-o` 可用于 TTFF 阈值判断。若 `-A 4 -B 28` 通过，只能说明看到满足门限的卫星，不等同于已经获得经纬度定位点；真实定位结果应以 location callback、经纬度和 TTFF 为准。

# 以太网

开发板提供 RJ45 以太网接口，支持 10/100/1000 Mbps 通信速率。以太网默认通过 DHCP 获取网络配置；连接网线后，可查看接口 IP、默认路由和 DNS 配置。

```bash
ifconfig eth0 2>/dev/null || ip addr show eth0
ip route
cat /etc/resolv.conf
ping -c 4 8.8.8.8
ping -c 4 www.example.com
```

若接口无 IP，应检查网线、交换机/路由器、DHCP 服务和接口状态。若 IP 正常但域名无法访问，应进一步检查 DNS 配置。

# 音频功能

音频系统基于 ALSA 与上层音频服务组成。硬件包含输入和输出通道，可用于板载麦克风、耳机麦克风、扬声器或耳机播放。操作前需确认硬件连接和音频配置文件状态。

```bash
cat /proc/asound/cards
cat /proc/asound/pcm
```

录音和播放可使用镜像提供的 `tinymix`、`agmcap`、`aplay` 或其他音频工具。录音前需确认采集通路、mixer 配置、采样率、通道数和设备名；播放前需确认输出通路和音量。若声卡或 PCM 流不存在，ALSA 与上层音频服务均无法正常工作。

# USB 功能

开发板提供多个 USB Type‑A 接口和 USB Type‑C 接口。板载 USB 模式可通过拨码开关在 Device 和 Host 场景间切换。

**USB Device 模式：** 设备作为 USB 从设备，由上位机识别和控制，适用于 ADB、固件烧录和上位机数据交互。该模式下不能外接 U 盘、键鼠等 USB 外设。

**USB Host 模式：** 设备作为 USB 主机，主动识别并驱动 U 盘、键鼠、USB 摄像头等外设，并向普通 USB 外设供电。

```bash
dmesg | grep -i usb
lsusb
ls /dev/video* 2>/dev/null
fdisk -l
df -h
```

USB 摄像头可通过 `v4l2-ctl` 查看节点、格式和分辨率；U 盘可通过块设备、挂载点和文件系统状态确认。

# SD 卡

开发板配备 micro SD + Nano SIM 二合一卡座，上方为 micro SD 卡座，下方为 Nano SIM 卡座。插入 SD 卡后，可通过块设备、挂载信息和挂载目录确认系统识别状态。

```bash
fdisk -l
df -h
ls /mnt/sdcard
```

如需手动挂载，可创建挂载目录并挂载对应分区；使用完毕后建议先卸载再拔卡，避免数据损坏。

```bash
mkdir -p /media/sdcard
mount /dev/mmcblk1p1 /media/sdcard
ls /media/sdcard
umount /media/sdcard
```

普通用户访问 SD 卡遇到权限不足时，可根据实际用户和挂载策略调整目录所有权或权限。

# ADC 功能

ADC 子系统用于将外部模拟电压转换为数字量。测试时可使用可调直流电源作为输入信号源，将电源正极连接到 ADC0 或 ADC1，引脚 GND 与开发板 GND 共地。各通道节点常见如下：

| **通道** | **节点** | **说明** |
| --- | --- | --- |
| ADC0 | `in_voltage_adc_gpio4_input` | 对应 GPIO4 ADC 输入。 |
| ADC1 | `in_voltage_adc_gpio7_input` | 对应 GPIO7 ADC 输入。L1 是否支持以具体硬件为准。 |

```bash
cd /sys/bus/iio/devices/iio:device0
cat in_voltage_adc_gpio4_input
cat in_voltage_adc_gpio7_input
```

读取值通常以微伏（μV）为单位。测试前必须确认输入电压范围，避免超过硬件允许范围。

# 40‑Pin 扩展接口

40‑pin 扩展接口支持 GPIO、I2C、SPI、UART、PWM 等功能。使用前必须核对引脚定义、电源脚、GND 和信号电平，避免误接导致外设或开发板损坏。

## GPIO

GPIO 可通过 sysfs 节点导出、设置方向并读写电平。实际 GPIO 编号以对应硬件表和系统节点为准。

```bash
echo 481 > /sys/class/gpio/export
echo out > /sys/class/gpio/gpio481/direction
echo 1 > /sys/class/gpio/gpio481/value
```

## I2C

I2C 使用前需确认总线已启用并生成 `/dev/i2c*` 节点，可使用 `i2cdetect` 查看设备地址，再用 `i2cget` / `i2cset` 读写寄存器。

```bash
40Pin-ctrl common_i2c enable
ls -al /dev/i2c*
i2cdetect -y 1
i2cget -y 1 0x53 0x05 b
i2cset -y 1 0x53 0x05 0x03 b
```

## SPI / UART / PWM

SPI 可通过 `/dev/spidev*` 节点确认，常用于 OLED、传感器等外设；UART 可用于串口回环或外部串口模块；PWM 可用于蜂鸣器、背光或其他脉冲控制场景。测试前需确认引脚复用状态、设备树配置、外设供电和信号电平。

```bash
ls /dev/spidev* 2>/dev/null
ls /dev/ttyHS* /dev/ttyMSM* 2>/dev/null
ls /sys/class/pwm/ 2>/dev/null
```

# 建议使用顺序

1. 先确认供电入口、适配器能力、拨码开关和外设连接状态。

2. 首次调试优先使用 ADB 或 Debug UART，确保能进入 Linux Shell。

3. 需要远程维护时，先配置以太网、Wi‑Fi 或蜂窝网络，再使用 SSH / SCP。

4. 需要图形界面时，再配置 RDP、TeamViewer 或本地 MIPI / HDMI 显示。

5. 外设验证按显示、摄像头、音频、USB、SD 卡、ADC、40‑pin 扩展逐项进行。

6. 遇到异常时，优先确认硬件连接，再查看节点、服务状态、日志和网络路由。

# 注意事项

- 供电不足会导致大量非确定性问题，包括启动失败、外设掉线、文件系统异常和网络不稳定。

- MIPI、摄像头、40‑pin、ADC 等接口测试前必须确认接线和电压范围。

- 远程桌面、Samba、Apache、TeamViewer 等网络服务应按实际产品安全要求启用，不需要时不建议默认开放。